<html>
  <head>
    <title>Encoding Utilities</title>
  </head>
  <body>
    <p>
      This package contains a number of utility classes dealing with generic
      encoding of {@link java.lang.String}s.
    </p>
    <p>
      Although this might sound useless at first (as {@link java.lang.String}s
      do support encoding internally already), this class deals with a very
      subtle problem encountered when merging Java {@link java.lang.String}s
      and old byte-based (non internationalized) transports, such as
      Base 64 and URL encoding.
    </p>
    <p>
      Let's consider (as an example) the URL encoded {@link java.lang.String}
      <code>%C2%A3 100</code> can be easily decomposed in a byte array using
      URL decoding techniques: we would end up with the following byte array:
      <code>0x0C2 0x0A3 0x20 0x31 0x30 0x30</code>.
    </p>
    <p>
      This byte-array, though, doesn't tell us anything about how to represent
      this as a readable and usable {@link java.lang.String} in Java. To be
      able to convert this we have to decode it again using a charset (or an
      encoding).
    </p>
    <p>
      So, for example, if we were to decode the above mentioned byte array using
      the <b>ISO-8859-1</b> encoding, we would obtain the string
      &quot;<code>&Acirc;&pound; 100</code>&quot;, or in details:
    </p>
    <ul>
      <li>a latin capital letter &quot;A&quot; with a circumflex accent</li>
      <li>the pound sign</li>
      <li>a space</li>
      <li>the number 1</li>
      <li>the number 0</li>
      <li>the number 0</li>
    </ul>
    <p>
      If we were to decode the same byte sequence using <b>UTF-8</b>, on the
      other hand, we would obtain the (quite different) string
      &quot;<code>&pound; 100</code>&quot;, or in details:
    </p>
    <ul>
      <li>the pound sign</li>
      <li>a space</li>
      <li>the number 1</li>
      <li>the number 0</li>
      <li>the number 0</li>
    </ul>
    <p>
      Therefore, as a conclusion, when Java {@link java.lang.String}s are
      encoded using Base 64, URL encoding, or similar techiques, one always
      have to remember that encoding (or decoding) must be done twice, and
      this package provides a way to deal with this mechanism.
    </p>
  </body>
</html>